Qt5.7文档翻译：QSslConfiguration类,QSslConfiguration Class

QSslConfiguration 类，记录的是单个SSL 连接的配置选项和状态。 详细说明……

注意 ： 这个类中的所有函数都是 可重入的 。

详细说明

QSslConfiguration 类，记录的是单个SSL 连接的配置选项和状态。

QSslConfiguration 被用在Qt的网络相关类中，用于传递单个处于开启状态 的SSL 连接的信息，并且 可用来控制那个连接的某些选项。

QSslConfiguration 目前支持 以下选项：

• •. 要使用的SSL/TLS协议

• •. 要向本地节点提供的证书，以及与之相关联的私钥

• •.允许在连接中使用的加密算法

• •.用来验证节点证书的权威证书机构（Certificate Authorities）证书列表

这些选项，只在连接的握手阶段有用。在连接建立之后，再设置这些选项，就不会有效果。

QSslConfiguration 支持 以下状态：

• •.握手阶段，由节点提供的证书，以及，往上直到权威认证机构的证书链

• •.用于对这个会话进行加密的算法

这些状态信息，只有在SSL 连接开始建立之后才能获取，但并不一定要在它完成之前获取。某些选项，可能会在SSL 连接保持的过程中发生改变，并且不会导致连接重新建立(例如，加密算法就可以发生改变)。

QSslConfiguration 对象 中的状态，无法人为改变。

QSslConfiguration 可与 QSslSocket 和网络访问应用编程接口（Network Access API）配套使用。

注意 ， 当妳改变 QSslConfiguration 中的选项时，并不足以改变其相关的SSL 连接的选项。 妳必须调用setSslConfiguration，传入一个修改过的 QSslConfiguration 对象，以实现那个目的。 以下示例，展示的是，如何将某个 QSslSocket 对象的协议改变成TLSv1_0：

QSslConfiguration config = sslSocket.sslConfiguration();

config.setProtocol( QSsl ::TlsV1_0);

sslSocket.setSslConfiguration(config);

参考 QSsl::SslProtocol 、 QSslCertificate 、 QSslCipher 、 QSslKey 、 QSslSocket 、 QNetworkAccessManager 、 QSslSocket::sslConfiguration () 和 QSslSocket::setSslConfiguration () 。

成员类型文档

enum QSslConfiguration::NextProtocolNegotiationStatus

成员函数文档

QList < QByteArray > QSslConfiguration:: allowedNextProtocols () const

这个函数，返回的是，之前使用 setAllowedNextProtocols ()设置 的，允许 与服务器之间就下个协议协商（Next Protocol Negotiation (NPN)）这个TLS 扩展所协商的协议列表。

此函数是从Qt 5.3 开始引入的。

参考 nextNegotiatedProtocol () 、 nextProtocolNegotiationStatus () 、 setAllowedNextProtocols () 、 QSslConfiguration::NextProtocolSpdy3_0 和 QSslConfiguration::NextProtocolHttp1_1 。

QList < QSslCertificate > QSslConfiguration:: caCertificates () const

返回 这个连接中使用的权威认证机构证书数据库。权威认证机构证书数据库 ，被套接字用来在握手阶段验证对端节点的证书。 可在握手之前使用 setCaCertificates ()或 QSslSocket 的 addCaCertificate() 和 addCaCertificates() 方法来修改。

参考 setCaCertificates () 。

QList < QSslCipher > QSslConfiguration:: ciphers () const

返回此连接当前使用的加密算法集合。这个列表，会在握手阶段被用于选择一个合适的会话加密算法。所返回的算法列表，是按照优先级降序排列的。(也就是说，列表中的第一个算法，是最优先使用的)。最终选择的会话加密算法，会是列表中第一个同时被对端节点所支持的算法。

默认情况 下，握手阶段中，可能 会选择被系统的SSL 库所支持的任何一个算法，而具体的支持情况依系统而定。 本系统 的SSL 库 所支持的算法列表，可由QSslSocket::supportedCiphers()来获取。 妳可以 将本套接字所要使用的会话加密算法列表限制在某个范围内，具体做法就是，调用 setCiphers () ，传入所有被支持的算法的一个子集。 妳可将候选算法列表恢复成整个集合，具体做法就是，调用 setCiphers ()时，传入QSslSocket::supportedCiphers()所返回的列表。

参考 setCiphers () 和 QSslSocket::supportedCiphers () 。

[static] QSslConfiguration  QSslConfiguration:: defaultConfiguration ()

返回用于新SSL 连接的默认SSL 配置。

默认SSL 配置，包含以下内容：

• •. 无本地证书，无私钥

• •.协议为SecureProtocols(表示使用TLS 1.0或SSL 3)

• •.使用系统的默认权威认证机构证书列表

• •.加密算法列表，包含着SSL 库中所支持的128 位及更高位数的SSL 加密算法列表

参考 QSslSocket::supportedCiphers () 和 setDefaultConfiguration () 。

QVector < QSslEllipticCurve > QSslConfiguration:: ellipticCurves () const

返回此连接中当前的椭圆曲线列表。这个列表，会在握手阶段用于选择一个椭圆曲线(前提是使用椭圆曲线加密算法)。所返回的曲线列表，按照优先级降序排列(也就是说，列表中的第一个曲线就是最优先使用的曲线)。

默认情况下，握手阶段可能选择系统SSL 库中支持的任何一个曲线，具体的支持情况依系统而定。系统SSL 库所支持的曲线列表，可由QSslSocket::supportedEllipticCurves()来获取。

妳可以将本套接字所使用的会话加密算法的候选列表限制在某个范围内，具体做法就是调用 setEllipticCurves ()，传入所支持的加密算法的一个子集。 妳也可以恢复成使用全部的集合作为候选列表，具体做法就是，调用 setEllipticCurves ()时传入QSslSocket::supportedEllipticCurves()所返回的列表。

此函数是从Qt 5.5 开始引入的。

参考 setEllipticCurves 。

QSslKey  QSslConfiguration:: ephemeralServerKey () const

返回用于前向加密（forward secrecy）的加密算法（cipher algorithms）的临时服务器密钥（ephemeral server key），例如，DHE-RSA-AES128-SHA。

只有 在运行于客户端模式，即 QSslSocket::SslClientMode 模式时，才能够使用临时密钥。如果运行 于服务器模式，或者，使用了某个不支持前向加密的加密算法，那么，会返回一个无效（null）的密钥。临时服务器密钥 ，会在发射encrypted()信号之前被设置。

此函数是从Qt 5.7 开始引入的。

QByteArray  QSslConfiguration:: nextNegotiatedProtocol () const

这个函数，返回的是，在启用了下个协议协商（Next Protocol Negotiation (NPN)）这个TLS 扩展的情况下，与服务器协商得到的协议。 要想启用NPN 扩展，则，在向服务器发起连接之前必须显式地调用 setAllowedNextProtocols ()。

如果没有任何 可协商的协议，或者尚未启用该扩展，那么，此函数返回一个无效（null）的 QByteArray 。

此函数是从Qt 5.3 开始引入的。

参考 setAllowedNextProtocols () 和 nextProtocolNegotiationStatus () 。

NextProtocolNegotiationStatus  QSslConfiguration:: nextProtocolNegotiationStatus () const

此函数，返回下个协议协商（Next Protocol Negotiation (NPN)）的状态。如果 该特性尚未通过 setAllowedNextProtocols ()启用，那么，此函数返回 NextProtocolNegotiationNone 。 这个状态，会在发射信号encrypted()之前被设置。

此函数是从Qt 5.3 开始引入的。

参考 setAllowedNextProtocols () 、 allowedNextProtocols () 、 nextNegotiatedProtocol () 和 QSslConfiguration::NextProtocolNegotiationStatus 。

QSslCertificate  QSslConfiguration:: peerCertificate () const

返回对端节点的数字证书(也就是说，妳所连接到的主机本身所具有的证书)，或者一个无效的（null）证书，以表明该节点未拥有证书。

对端节点的证书，是在握手阶段自动检查的，因此，本函数一般是用于获取该证书以进行显示或者连接诊断目的。它包含着与对端节点相关的信息，包括主机名、证书颁布者和对端节点的公钥。

因为对端节点 的证书是在握手阶段设置的，所以， 可以安全地在与 QSslSocket::sslErrors ()信号、 QNetworkReply::sslErrors ()信号或 QSslSocket::encrypted ()信号相连接的信号槽中访问对端节点的证书信息。

如果返回了一个无效证书，那么，可能是因为SSL 握手失败，或者妳所连接到的主机并不拥有证书，或者可能根本就没有建立连接。

如果 妳想检查对端节点的完整证书链，那么，可使用 peerCertificateChain ()来一次性全部获取。

参考 peerCertificateChain () 、 QSslSocket::sslErrors () 、 QSslSocket::ignoreSslErrors () 、 QNetworkReply::sslErrors () 和 QNetworkReply::ignoreSslErrors () 。

QSsl::SslProtocol  QSslConfiguration:: protocol () const

返回这个SSL 配置的协议选项。

参考 setProtocol () 。

QSsl::SslProtocol  QSslConfiguration:: sessionProtocol () const

返回本套接字的SSL/TLS协议，或者，如果连接尚未加密成功则返回UnknownProtocol。套接字的会话协议，是在握手阶段设置的。

此函数是从Qt 5.4 开始引入的。

参考 protocol () 和 setProtocol () 。

void  QSslConfiguration:: setAllowedNextProtocols ( QList < QByteArray >  protocols )

这个函数，用来通过 下个协议协商（Next Protocol Negotiation (NPN)）这个TLS 扩展来设置允许与服务器之间协商的协议为 protocols ； protocols 中的每个元素，都必须表示一个被允许的协议。 这个函数必须在建立连接之前显式调用，以使得在 SSL 握手阶段发送NPN 扩展。至于协商 是否成功，可通过 nextProtocolNegotiationStatus ()来查询。

此函数是从Qt 5.3 开始引入的。

参考 nextNegotiatedProtocol () 、 nextProtocolNegotiationStatus () 、 allowedNextProtocols () 、 QSslConfiguration::NextProtocolSpdy3_0 和 QSslConfiguration::NextProtocolHttp1_1 。

void  QSslConfiguration:: setEllipticCurves (const  QVector < QSslEllipticCurve > & curves )

将本套接字要使用的椭圆曲线列表设置为 curves ，其中包含 的必须是由 supportedEllipticCurves ()所返回的曲线列表的一个子集。

对椭圆曲线列表的范围限制，必须在握手阶段之前进行，也就是在会话加密算法的选择之前进行。

此函数是从Qt 5.5 开始引入的。

参考 ellipticCurves 。

void  QSslConfiguration:: setProtocol ( QSsl::SslProtocol protocol )

将这个配置中使用的协议设置为 protocol 。

在连接建立之后再设置协议的话，没有什么卵用。

参考 protocol () 。

void  QSslConfiguration:: setSslOption ( QSsl::SslOption option ,  bool on )

启用或禁用SSL 中的某个兼容性选项 option 。如果 on 为真（true），则选项 option 被启用。如果 on 为假（false），则选项 option 被禁用。

参考 testSslOption () 。

bool  QSslConfiguration:: testSslOption ( QSsl::SslOption option ) const

如果指定 的SSL 兼容性选项 option 被启用，则返回真（ true ）。

此函数是从Qt 4.8 开始引入的。

参考 setSslOption () 。

成员变量文档

const char QSslConfiguration::NextProtocolHttp1_1[]

const char QSslConfiguration::NextProtocolSpdy3_0[]

这个变量，其中储存的值，被用于在下个协议协商（Next Protocol Negotiation）中对SPDY 3.0 进行协商。

未知美人

橙小酱

未知美人

雅卿